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Preface 


Flask started as a project to show you how you can build your own framework on existing Python 
toolkits. Actually, Flask started as an April Fool's joke in 2010. Several microframeworks had 
been appearing in the Python community, offering their own set of interfaces to build web 
services and applications entirely in one . py file. Having built Werkzeug (a web programming 
toolkit) and Jinja (a templating engine), Armin Ronacher zipped these two projects, put the 

zip file base64-encoded into a . py file, added a few small functions, and called it the Denied 
microframework. 


The April 1st marketing site for Denied included a working "Hello World" application in a few 
lines of code, a spoof screencast, some bogus testimonials, zero documentation, and a few 
hints that you should not trust everything you read on the Internet. Denied was a critique on 
how an open source project can go wrong—mostly through missing documentation and design 
flaws that can cause serious issues in production programs. 


This was Flask's beginning, the microframework with good intentions. Flask aimed to 

provide a good developer experience through clear, simple interfaces packaged with 

useful documentation, a thorough test suite, and careful thought to production issues and 
backward/forward-compatibility across releases. Flask demonstrated how to build a thin layer 
on top of Werkzeug and Jinja. Then Flask became popular on its own, developed a community, 
and now several Flask-built applications are in production, small and large. 


As a contributor to the Flask project, | observed that most new users ask questions of the 
form, "what is the Flask way to do X?" Most of the time, the question is better stated as, "what 
is the Python way to do X?" Flask does not have many options about how you use it, which 
makes it a great tool to start simply and grow carefully without fighting the options, deeply 
embedded in the framework as your project gets large. 
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That said, when you are getting started with Flask, you will wonder how a representative 
application looks. This book will Show you just that. | have condensed my own experience with 
Flask into a small but complete application which we will build bottom-up one piece at a time. 
Along the way, | will provide pointers as you make considerations in your own projects. If, by 
the end of this book, you want more, take a look at the scheduler application that we built, 
identify areas where you would like to design your own improvements, and use these areas 
for projects to exercise your web development skills. 


What this book covers 
Preparing for development (Simple) explains how to set up your development environment and 
ensure that you have everything in place for developing web projects with Python and Flask. 


Running a simple application (Simple) shows how to warm up with the simplest "Hello World" 
Flask application. 


Routing URLs and accepting requests (Simple) shows how to start your project by accepting 
web requests according to your URL rules. 


Handling requests and responses (Simple) explains how Flask handles web requests and 
how you can build responses. 


Handling static files (Simple) explains how to send files from disk as a response. 


Using a database (Simple) explains how to declare a data structure, store data with your 
application, and manage queries with SQLAIchemy. 


Handling forms and file uploads (Simple) explains how to build a form with WTForms to 
match the application data structure, which provides HTML input and validates user input. 


Templating with Jinja - setting a base template (Simple) explains how to set the base HTML 
structure of your application, providing page structure and theme able CSS style with Twitter 
Bootstrap and JavaScript page manipulation with jQuery. 


Creating a new record (Intermediate) explains how to provide a web form to create a 
database record. 


Displaying a record (Intermediate) explains how to retrieve a record from the database and 
display it in HTML. 


Editing a record (Intermediate) explains how to provide a web form to edit an existing 
database record. 


Listing all records (Simple) explains how to build an index view to display all records from 
the database in HTML. 


Deleting a record (Advanced) explains how to add a JavaScript-triggered DELETE request 
to remove a record from the database. 


[2] 
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Using custom template filters in Jinja (Advanced) explains how to extend Jinja to include 
custom display formats for your data. 


Sending error responses (Simple) explains how to respond to errors with styled HTML pages. 


Authenticating users (Advanced) explains how to build a user data model which includes 
a hashed password field for authentication by credential that only the user would know. 


Handling sessions and users (Intermediate) explains how to keep users logged in for 
on-going requests after authentication. 


Deploying to the world (Advanced) explains how to publish your application with nginx 
and gunicorn on Ubuntu, with a pointer on how to deploy on any operating system 
using HTTP proxying. 


What you need for this book 


This book assumes that you have Python and an interest in web development. You need to 
know, or be willing to learn some Python and a little bit of the web technologies HTTP, HTML, 
CSS, and JavaScript. This book specifically covers web development with Flask, which is a 
third-party package for the Python programming language. If you are new to Python or web 
development, be sure to have good resources on hand for the Python language and the 
various web technologies. 


At the time of this writing, Flask is version 0.10, which is stable and production-ready. From 

its beginning, the Flask project has made every effort to maintain backward compatibility, 
providing upgrade instructions on major releases. See https: //pypi.python.org/pypi/ 
Flask for the latest version and installation instructions for Flask. 


This book uses virtualenv to install third-party packages, which is version 1.9 at the time of 
this writing. Note that virtualenv 1.9 adds SSL support when installing packages, so if you 
already have virtualenv installed, be sure to upgrade. See https: //pypi.python.org/ 
pypi/virtualenv for the latest version and instructions for virtualenv. 


[ GA This book uses both Python 2.7 and Python 3.3. | 


At the time of this writing, Flask supports Python 3.3+ as of its 0.10 release. Packages 
available in the community, however, do not always have Python 3 support. | encourage you to 
use Python 3 in your projects. The Python community is still in transition to Python 3, which is 
backward-incompatible with Python 2, but investing in Python 3 now will allow you to grow your 
codebase with modern Python, where new features are being added to the language. 
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If you are using a Python implementation other than CPython, such as pypy, download the 
Flask source and run its tests to verify that Flask is compatible with your interpreter. 


Other materials are listed in the Checklist for Develooment Environment section under the 
Preparing for development recipe. 


Who this book is for 


This book is for readers who are new to web programming, or are familiar with web 
programming but new to Flask. This book is intended for three classes of readers: 


>» Programmers getting started in web development, starting with an interest in Python 
towards a working knowledge of how to build web applications 


>» Programmers who are familiar with web development, starting with a working 
knowledge of how to build applications in a familiar language (which may or may not 
be Python) towards the use of Flask in daily work 


» Designers who have decided to learn programming, starting with a user interface 
design in mind toward a self-built functional application 


In all the three cases, Flask is well suited as a starting place for web development in Python, 
and Python as a language is accessible to readers who are beginning to learn programming. 


Conventions 


In this book, you will find a number of styles of text that distinguish between different kinds of 
information. Here are some examples of these styles, and an explanation of their meaning. 


Code words in text, database table names, folder names, filenames, file extensions, 
pathnames, dummy URLs, user input, and Twitter handles are shown as follows: "This creates 
a Python object app, which is a WSGI application." 


A block of code is set as follows: 
from flask import Flask 
app = Flask(__name_) 
@app.route('/') 


def hello(): 
return 'Hello, world!' 
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When we wish to draw your attention to a particular part of a code block, the relevant lines or 
items are set in bold: 


from flask import Flask 
app = Flask(_ name_) 
@app.route('/') 


def hello(): 
return 'Hello, world!' 


Any command-line input or output is written as follows: 
$ python manage.py runserver -t 0.0.0.0 -p 8080 


New terms and important words are shown in bold. Words that you see on the screen, in 
menus or dialog boxes for example, appear in the text like this: "We reuse the same template 
as the create form, but we say Edit instead of Add." 


[ % Warnings or important notes appear in a box like this. | 


M 
[ Q Tips and tricks appear like this. ] 


Reader feedback 


Feedback from our readers is always welcome. Let us know what you think about this 
book—what you liked or may have disliked. Reader feedback is important for us to develop 
titles that you really find useful. 


To send us general feedback, simply send an e-mail to feedback@packtpub.com, and 
mention the book title via the subject of your message. 


If there is a book that you need and would like to see us publish, please send us a note in the 
SUGGEST A TITLE form on www. packtpub.com or e-mail suggest @packtpub. com. 


If there is a topic in which you have expertise, and you are interested in either writing or 
contributing to a book, see our author guide on www. packtpub.com/authors. 
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Customer support 


Now that you are the proud owner of a Packt book, we have a number of things to help you to 
get the most from your purchase. 


Downloading the example code 


You can download the example code files for all Packt books you have purchased from your 
account at http: //www. Packt Pub.com. If you purchased this book elsewhere, you can visit 
http://www. PacktPub.com/support and register to have the files e-mailed directly to you. 


Errata 


Although we have taken every care to ensure the accuracy of our content, mistakes do happen. 
If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be 
grateful if you would report this to us. By doing so, you can save other readers from frustration 
and help us improve subsequent versions of this book. If you find any errata, please report them 
by visiting http: //www.packtpub.com/support, selecting your book, clicking on the errata 
submission form link, and entering the details of your errata. Once your errata are verified, your 
submission will be accepted and the errata will be uploaded on our website, or added to any 

list of existing errata, under the Errata section of that title. Any existing errata can be viewed by 
selecting your title from http://www. packtpub.com/support. 


Piracy 


Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, 
we take the protection of our copyright and licenses very seriously. If you come across any 
illegal copies of our works, in any form, on the Internet, please provide us with the location 
address or website name immediately so that we can pursue a remedy. 


Please contact us at copyright @packtpub.com with a link to the suspected pirated material. 


We appreciate your help in protecting our authors, and our ability to bring you valuable content. 


Questions 


You can contact us at quest ions@packtpub. com if you are having a problem with any 
aspect of the book, and we will do our best to address it. 
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Instant Flask 
Web Development 


Welcome to Instant Flask Web Development. We will progressively walk through web 
development in the Python programming language using Flask, a small but expressive 
framework which provides the essentials and enables you to build your own code patterns. 
We will build a simple scheduling application to keep track of appointments, including 

a database and a user interface, and we will build one piece at a time. We will build our 
application bottom-up, and you will see how everything fits together in later sections. This 
bottom-up approach will give you the building blocks you need to grow your project with Flask. 


Preparing for development (Simple) 


We begin our exploration of Flask web programming with everything in its place, setting up a 
development environment in Python. 


Getting ready 


Go to python. org to get Python. Our application will run on Python 2.7 and Python 3.3+. 
Once you have Python, you do not need administrative access to your development machine, 
and you can even install Python for just your user according to the install instructions on 
python.org. 


How to do it... 


Python projects can manage packages using virtualenv, a user-writable area on the machine 
that is dedicated to a specific project. You can use virtualenv on Unix/Unix-like systems, Mac 
OS X, and Windows. 
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We'll use the command line to get virtualenv up and running, then discuss the tools you need 
in your development environment. Before we get started, note the Common Errors and how to 
solve them subsection in the There's more... section in case you run into a problem. 


Unix-style systems ship with a terminal emulator, which we will use throughout this book. 
The steps required to install Flask on Unix, Unix-like systems, and Mac OS X are as follows: 


A 
2. 


Open a terminal in the directory where you would like your project to be located. 


Download virtualenv from pypi.python.org/pypi/virtualenv/1.9.1. Inthe 
terminal, you can do this with curl -O https://pypi.python.org/packages/ 
source/v/virtualenv/virtualenv-1.9.1.tar.gz. 


Unpack virtualenv with tar xvzf virtualenv-1.9.1.tar.gz. 


Create a virtualenv tool named env with python virtualenv-1.9.1/ 
virtualenv.py env. You can use any name you like; just be sure to make the 
changes in the commands here according to the name you choose. 


Activate the virtualenv tool with . env/bin/activate. 
Install Flask with pip install Flask. 


Verify whether Flask is installed with a simple smoke test, python -m flask. 
config. Nothing will be displayed if Flask is installed. 


You can turn off the virtualenv with deactivate to continue using the terminal for other 
projects. Anytime you resume work on your Flask project, activate the virtualenv again with 
. path/to/env/bin/activate. The . command sources the activate script to set 
environment variables that point to the python executable in the virtualenv and enable 
import of the packages installed there. 


For Windows, we will use cmd . exe. The steps to install Flask on Windows are as follows: 


1. 


Ensure the Python installation and its scripts directory, which are C: \Python33 \ 
and C: \Python33\Scripts\ by default, are in your current PATH variable. Use 
Python27 if you are using Python 2.7, and note that Windows uses a semicolon 
in-between directories in PATH. Use echo %PATH% to see your PATH variable. 

In general, edit PATH by navigating to Computer | Properties | Advanced | 
Environment Variables. 


Open a shell in the directory where you would like your project to be located. 
Historically, you could run into scripts which fail on spaces in the filepath, which is 
why C: \Python27\ is preferred to C:\Program Files\Python27\; keep that 
in mind if you see strange errors. 


Download virtualenv.py from https: //raw.github.com/pypa/ 
virtualenv/1.9.1/virtualenv.py to the same directory. 


Create a virtualenv named env with python virtualenv.py env. You can 
use any name you like; just be sure to make the changes in the commands here 
according to the name you chose. 
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5. Activate the virtualenv with env\Scripts\activate.bat. 
Install Flask with pip install Flask. 


7. Verify whether Flask is installed with a simple smoke test, python -m flask. 
config. Nothing will be displayed if Flask is installed. 


You can turn off the virtualenv tool with deactivate to continue using the command prompt 
for other projects. Anytime you resume work on your Flask project, activate the virtualenv tool 
again with env\Scripts\activate.bat, which is a batch file to set environment variables 
that point to the python executable in the virtualenv and enable import of the packages 
installed there. 


If you are using Windows, you can use PowerShell for a 
si richer command-line environment by referring to technet. 


microsoft.com/en-us/library/bb978526.aspx, or you 
can work with cmd. exe if you do not have access to PowerShell 
by referring to docs. python.org/2/using/windows.html. 


Python itself ships with a large collection of utilities in its standard library. With Python out of 
the box, you can immediately use any of the code listed at docs. python.org/2/library/. 
The Python interpreter has several functions and objects which are always available, and 
several more which become available with an import statement as shown: 


import antigravity 


The Python community adds even more modules to import through collaborations on 
frameworks (including Flask) and toolkits published to the Python Package Index, PyPI 
(pronounced "pie p.i."), at pypi . python. org. Packaging gets complicated, and pip and 
virtualenv aim to make a manageable workflow around use of third-party packages on PyPI. 


There's a lot more that can be achieved as follows: 


Checklist for the development environment 
Here are the items you need to develop a web application: 
>»  Atext editor for adding and editing source code. | use emacs and vim, which have 


highly productive keyboard shortcuts, and Sublime Text is a popular choice. There are 
many options; just be sure the editor is designed for code. 


>» Python with a virtualenv tool, using the instructions in this chapter. 
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>» Aterminal console to run your Flask code, one for each Flask application you run, as 
discussed in the next section. 


>» Aterminal console to run Python's interactive interpreter. Here you can poke at APIs, 
experiment with code, verify unit functionality, and use Python's built-in help (arg) 
function to get online documentation. 


>» Amodern web browser. Firefox and Chrome have readily accessible JavaScript 
consoles and document inspectors for web pages. The JavaScript console and 
document inspector are essential for web user interface development. 


» Flask docs available at: flask.pocoo.org/docs/. 


>» Werkzeug docs available at: werkzeug.pocoo.org/docs/. Werkzeug is Flask's 
underlying web service implementation. 


>» Jinja docs available at: jinja.pocoo.org/docs/. Jinja is Flask's default 
template engine. 


» Python docs available at: docs.python.org/2/. 


» Version control system. Track changes to your project. | personally recommend git, 
available at git-scm. com. 


An integrated development environment (IDE) can bundle these tools together in one 
application, and there are several available for Python. Personally, | find the best tool for 

each item in the checklist and put together my own environment as a collection of standalone 
tools and applications. | highly recommend having a stand-alone command-line available for 
code interaction, so that you can always get to the core of your code even if you have an IDE 
that you like. 


(I find myself to be more productive doing everything on the command-line and in the terminal, 
but that's a matter of personal preference. Be sure to love your development environment, so 
that you can think clearly about your work.) 


Common errors and how to solve them 
Two common errors you will see in using a Python virtualenv are: 


>» The python command is not found when you attempt to run Python 
>» "No module named flask" when you attempt to import Flask in your code 


Both issues are caused by an incorrect environment variable named PATH in your 
command-line session, which is an ordered list of directories your system should search 
when loading a command. If python is not found, your PATH was not updated when you 
installed Python and you should revisit the Python installer. If flask is not found, you have 
either not activated your virtualenv or you have not installed Flask, and you should revisit 
the install instructions here. 
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Running a simple application (Simple) 


Let's get started by running a simplest Flask application. 


Getting ready 


Make sure you have activated your virtualenv tool as described in the previous section. 


How to do it... 


1. Put this code into a file named hello. py: 
from flask import Flask 


app = Flask(__name_) 
@app.route('/') 
def hello(): 


return 'Hello, world!' 


if name = 
app.run() 


2. Run this application from the console: 
$ python hello.py 


3. If this runs correctly, you will see: 


* Running on http://127.0.0.1:5000/ 


This is a URL, which you can visit in your browser. When you do, your browser will 
display a plain page which says "Hello, world!" (without quotes). Note that the 
address 127.0.0.1 refers to localhost, such that Flask will only respond to requests 
from the host running the code. 


Line-by-line, here is what this code does: 


app = Flask(__name_) 
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This creates a Python object app, which is a WSGI application. WSGI stands for Web Service 
Gateway Interface, and is the Python community's standard interface for hosting web 
projects. Any WSGI resource or tool that you find, you can apply to this app object, including 
WSGI middleware (if you do, wrap app.wsgi_app) and HTTP servers such as gunicorn or 
Apache httpd with mod_wsgi. 


The argument given to the Flask class tells Flask how to find resources associated with 
your application: static files and templates. Passing name ___ tells Flask to look at the 
current Python module—the . py file containing this code. Most of your applications will use 
___name__; the Flask docs describe this parameter in detail if you ever suspect _ name ___is 
not fulfilling your needs. 


The next block sets up a function to handle web requests to the '/' URL: 


@app.route('/') 
def hello(): 
return 'Hello, world!' 


Every time Flask gets a request to the '/' URL, it will call the hello function. The Python 
web community calls these routed functions view functions. In general, view functions in Flask 
return strings for web responses, and here we provide a simple "Hello, world!" response for all 
the requests, to prove that things are working. 


The final block tells Python to run a development web server, but to only do so if the current 
. py file is being called directly: 


if name == ' main ': 


That is, this code block will run if you run the command python hello.py but not if you use 
import hello from another Python module. 


Once you are satisfied with the Hello World application, let's structure our project. 


Project layout 


We will be building a simple scheduling application to manage appointments and display 
them. Let's move our one-file application into a directory setup for a larger application. Create 
the following file layout in your project, with a sched directory which contains subdirectories 
static and templates, both currently empty. 


manage.py 
requirements .txt 
sched/ 


[12] 
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app . py 
config.py 
filters.py 
forms .py 
init__.py 
models .py 
static/ 
templates/ 


Move hello.py to app. py inside the sched directory. The _ _init__.py file is an 

empty file telling Python that sched is a package containing Python files. The config. py, 
filters .py, forms .py, and models . py files are currently empty files which we will fill in 
the upcoming sections. 


Development server 
If you need to access your Flask application from another machine on the network, use: 


app.run('0.0.0.0') 


The default port for Flask's development server is 5000, and we will use localhost on port 
5000 throughout this book. If this is already in use, or you would like to use a different port, 
you can set it via the second argument to the run method, as follows. 


app.run('0.0.0.0', 8080) 


The development server given by app. run is for development only. When you are ready 

to publish your application, use an industrial strength web server as discussed in the later 
section on deploying and logging. Because we are using app. run for development only, 
let's turn on the debug mode, which will provide an interactive debugger in the web browser 
when uncaught exceptions occur and will reload code on changes to existing Python files in 
your project. You should only use '0.0.0.0' and/or debug mode on a trusted network. Add 
debug=True to the run line, keeping any other arguments you already added: 


app. run (debug=True) 
Command-line interface with Flask-Script 
We will use manage. py to manage our application using Flask-Script, with these contents: 


from flask.ext.script import Manager 
from sched.app import app 


manager = Manager (app) 
app.config['DEBUG'] = True # Ensure debugger will load. 


if name == ' main ': 


manager. run () 
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The requirements. txt file is a conventional way to track all third-party Python packages. 
Set the file with the following listing, which is one package name per line. Run pip install 
-r requirements.txt with your virtualenv active and a working internet connection to 
install these dependencies. 


Flask 
Flask-Script 


Now you can run your application with python manage.py runserver. Run python 
manage.py -hto get help and python manage.py runserver -hto get help on the 
development server options. Use python manage.py shell to get an interactive Python 
interpreter with the Flask application loaded, which you can use to inspect your code and 
try new things interactively. By default, Flask-Script gives you the runserver and shell 
commands; you can add custom manage . py subcommands; refer to the Flask-Script docs. 


As we discussed, you can make the development server accessible from another machine on 
the network and change the port; here is the command pattern: 


$ python manage.py runserver -t 0.0.0.0 -p 8080 


1 
Q Flask-Script added Python 3 support earlier this month. This book now 


fully supports Python 2 and Python 3. 


Routing URLs and accepting requests 


(Simple) 


This section will connect URLs to Python functions in our web service. 


Getting ready 


Use the project layout listed under the Project Layout section in the Running a Simple 
Application recipe. 
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How to do it... 


1. 


The Flask app object includes a route decorator to specify URL rules to use for a 
view function conveniently, which provides a declarative style for routing requests to 
Python callables. The following code routes five URL handling functions for the list, 
detail, creation, updating, and deletion of appointment records in our scheduling 
application. For now, we simply return a string describing what the handler is going 
to do, which we'll implement later, so that you can see the URL routing in action from 
your browser. Place into app. py: 


@app.route('/appointments/') 
def appointment _list(): 
return ‘Listing of all appointments we have.' 


@app.route('/appointments/<int:appointment_id>/') 
def appointment detail (appointment_id): 
return 'Detail of appointment #{}.'.format (appointment_id) 


@app. route ( 
'/appointments/<int:appointment_id>/edit/', 
methods=['GET', 'POST']) 


@app.route(...) and def appointment _edit(...). 


def appointment edit (appointment _id): 
return 'Form to edit appointment #.'.format (appointment_id) 


@app. route ( 
'/appointments/create/', 
methods=['GET', 'POST']) 
def appointment _create(): 
return 'Form to create a new appointment. ' 


@app. route ( 
'/appointments/<int:appointment_id>/delete/, 
methods=['DELETE'] ) 

def appointment delete (appointment id): 

raise NotImplementedError ('DELETE') 
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Downloading the example code 


a! You can download the example code files for all Packt books you have 
Q purchased from your account at http: //www.packtpub.com. 
If you purchased this book elsewhere, you can visit http: //www. 
packtpub.com/support and register to have the files e-mailed 
directly to you. 
2. Using python manage.py runserver, you can visit these URLs at: 

a http://localhost:5000/appointments/ 

Qa http://localhost:5000/appointments/1/ 

Qa http://localhost:5000/appointments/1/edit/ 


a http://localhost:5000/appointments/create/ 


Qa http://localhost :5000/appointments/1/delete/ 


If you test these URLs in your browser, you will find that the delete URL 
eS responds with a 405 Method Not Allowed error. This is intentional, because 
GA the browser sends a GET reuest by default and we are only allowing 
DELETE methods. We do not want to delete a record on a GET request, but 
only when our delete button is pressed (built in a later section). 


3. You can build URLs to your view functions using the flask.url_for function, 
which returns a string representation of the URL. This lets you program using clean 
identifiers in case URLs change, using the names of the target function and its 
arguments: 


from flask import url_for 


@app.route('/appointments/<int:appointment_id>/') 
def appointment detail (appointment_id): 
edit_url = url for('appointment_edit', 
appointment _id=appointment_id) 
# Return the URL string just for demonstration. 
return edit_url 


4. The first argument to url_for is called the endpoint, which by default is the name 
of the Python function wrapped by the app. route decorator. You can override the 
default using the endpoint keyword argument to app. route: 


@app . route ( 
'/appointments/<int:appointment_id>/', 
endpoint='some_name') 
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def appointment detail (appointment_id): 
# Use url for('some_name', appointment_id=x) 
# to build a URL for this. 
return 'Just to demonstrate...' 


The main argument to app. route is the string URL rule as implemented by Werkzeug, 
Flask's underlying toolkit for all things WSGI. Items listed in angle brackets <argument > 
are parsed as named arguments to pass into the view function. Flask uses a convention of 
<converter:argument> in the URL rule to parse the argument value before passing it to 
your view function, and only routing the URL if a value is correctly parsed. By default, Flask 
treats the argument as a string. The additional built-in converters are: 


>» int: The value of this converter is an integer 

> float: The value of this converter is a floating point number 

> path: The value of this converter is a string such as the default, but also 
accepts slashes 


You can define your own converters as shown in Flask's app. url_map documentation, but 
you may not need to, such that your view function can inspect the string argument and parse 
what it needs. 


By default, if a URL rule ends in a trailing slash /, Flask will redirect requests without the 
trailing slash to the handler which includes it. 


Once you are up and routing, there are a few things you should know about HTTP and 
Flask routes. 


Handling HTTP methods 
The most common keyword argument to app. route iS methods, giving Flask a list of HTTP 
methods to accept when routing, which when absent defaults to GET. Valid values are GET, 
POST, PUT, DELETE, HEAD, and OPTIONS. RFC2068 is a standards document which defines 
these methods. Briefly, they are: 

> GET: This option is used to reply with information on resource, most common 


> POST: This option is used to receive from browser/client updated information 
for resource 


>» PUT: This option is like POST, but repeat PUT calls on a resource should have no effect 
> DELETE: Using this option removes the resource 
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> HEAD: This option is like GET, but replies only with HTTP headers and not content 


> OPTIONS: This option is used to determine which methods are available for resource 


Flask implements HEAD for you if GET is present, and OPTIONS for you in 
lf all cases. Old implementations of HTTP browsers only supported GET and 
GA POST, but we will add a DELETE request by JavaScript in a later section. 
It is up to you and your project to use the other HTTP methods, particularly 
in cases where the semantics of the methods are important. 


An alternative to decorating functions 


The @app. route approach is a Python decorator, which you use at the time you define a 
function. As an alternative, you can use app.add_url_rule, which works exactly like app. 
route but is a simple method call and is not a decorator. You can provide app.add_url_ 
rule with any Python callable, accepting the parameters in the URL rule, which will become 
request .view_args at the time of the request. If you have your own ideas on how to 
specify the URL routes of your application, you can use whatever tools you like with app .add_ 
url_rule as a utility to wire up your Flask application. 


Route collisions 


When Flask routes your requests to unexpected places, look for collisions in your app. route 
calls. That is, if you have routes /<path: foopath> and /foo/bar/baz/, both will match 
on /f00/bar/baz/. The solution is to be as specific as possible in your route parameters, 
and avoid overly generic parameters. 


Routing with subdomains 
You can route subdomains using the subdomain keyword argument to app. route: 


@app.route('/', subdomain='<spam_eggs>') 
def subdomain_example(spam_eggs) : 
return "ass! 


This subdomain argument uses the same parameter approach as other URLs, but note that 
proper subdomains are limited in what they can accept. Simple names are straightforward, 
but if you have specific requirements, see RFC2181 for name syntax and note that some 
HTTP clients do not support the full spec in subdomains. 


When you use subdomains, Flask needs to know the server name in order to parse the 
subdomain from the URL. Provide SERVER_NAME to app. config, as described in the 
section on configuration. 
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You will also run into limitations while developing locally on your machine, because 
localhost does not accept subdomains. You can set your operating system's hosts file 
(typically /etc/hosts). If your SERVER_NAME iS example . com and your subdomain 
argument is foo, you can set: 


127.0 0.21. localhost local.example.com foo.local.example.com 


The hosts file does not accept wildcards. If you have access to a domain name service, an 
alternative to hosts file is to set an A record and all of its subdomains (wildcard) in DNS to 
127.0.0.1, like the following example. This will route all subdomains for local.example. 
com on all machines to the local host. 


local.example.com A 127.0.0.1 
* local.example.com A 127.0.0.1 


This technique requires a DNS network call, so if you are working offline, you'll need to fall 
back on the hosts file. 


Handling requests and responses (Simple) 


This section will demonstrate how Flask handles incoming data on HTTP requests and how 
you can send responses. 


Getting ready 


Set aside the scheduling application and open a new Python file to explore Flask. 


How to do it... 


1. Atthe core, Flask and Werkzeug provide request and response objects to represent 
incoming and outgoing data for your web application. Flask provides three different 
patterns for return values from your view functions: 


a string, which can optionally use a template engine (introduced later) 


a aresponse instance, an object with attributes representing HTTP response 
details 


a tupleof (string, status) or (string, status, http headers), 
for convenience, such that you do not have to create a response instance 
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2. 


Let's see each of the response patterns in action. Each response will say Hello, 
world! with a 200 OK status code (the typical HTTP response on success), and the 
latter two functions tell the browser to display the response as plain text. The first 
function's response displays as though it were HTML because a string-only return 
object has no means to tell Flask how to set the content-type of the response. 


from flask import Flask, make response 
app = Flask(__name_) 


@app.route('/string/') 
def return_string(): 
return 'Hello, world!' 


@app.route('/object/') 
def return_object(): 
headers = {'Content-Type': 'text/plain'} 
return make _response('Hello, world!', status=200, 
headers=headers) 


@app.route('/tuple/') 
def return_tuple(): 
return 'Hello, world!', 200, {'Content-Type': 
'text/plain'} 


As Flask prepares to call your view function and accepts its return value, it walks 
through each of the before-request and after-request callbacks you provide. Here, 
we set up a before-request function and an after-request function, purely for 
demonstration purposes to illustrate Flask's request and response handling. You can 
use these handlers to explore Flask behavior when you want to interact with what 
Flask docs are saying. When you run this code, keep in mind that browsers often 
automatically look for /fEavicon.ico, which can cause extra requests for your 
application when testing. 


from flask import request 


def dump_request_detail (request): 
request_detail = """ 

# Before Request # 

request.endpoint: {request.endpoint} 

request.method: {request .method} 

request.view args: {request.view args} 

request.args: {request.args} 

request.form: {request.form} 

request.user agent: {request.user_ agent} 

request.files: {request.files} 
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request.is xhr: {request.is xhr} 


## request.headers ## 

{request .headers} 
vu" format (request=request) .strip() 
return request_detail 


@app.before_ request 

def callme before every request (): 
# Demo only: the before request hook. 
app.logger.debug(dump_request_detail (request) ) 


@app.after_ request 

def callme_after_every_ response (response): 
# Demo only: the after request hook. 
app.logger.debug('# After Request #\n' + repr(response) ) 
return response 


Here are commonly used features of the request object. See the Flask docs for the full list of 
incoming request data. To provide an example, each description includes an example value 
for a request hitting /string/?foo=bar&foo=baz from our browser. 


>» endpoint: This feature of the request object specifies the name of the request 
endpoint routed, for example, return_string. 


> method: This feature of the request object specifies the HTTP method of the current 
request, for example, GET. 


> view_args: This feature of the request object specifies the dict of view function 
arguments parsed from URL route rule, for example, { }. 


>» args: This feature of the request object specifies the dict of arguments parsed 
from the URL query string, for example, request .args['foo'] iS 'bar' and 
request.args.getlist('foo') iS ['bar', 'baz']. 


>» form: This feature of the request object specifies the dict of form data from POST 
or PUT requests, for example, { }. 


> user_agent: This feature of the request object specifies the version identification 
provided by the browser. 


>» files: This feature of the request object specifies the dict of file uploads from POST 
or PUT requests, which go here instead of request . form, for example, {}. Each 
value in the dict is a FileStorage object which behaves like a Python file object, 
but also includes a save (filepath) method to store uploaded files (after you 
validate the destination path). 


[24] 
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> is xhr: True: This feature of the request object specifies when the incoming 
request is a JavaScript XMLHttpRequest, and False otherwise. This works with 
JavaScript libraries that provide the X-Requested-With HTTP header, set to 
XMLHttpRequest 


Flask uses a custom dict type ImmutableMultiDict which supports multiple values per 
key (accessed by the get list method), in cases where HTTP allows multiple values for a 
given argument, such as the query string in the URL, for example, ?foo=bar&foo=baz. 


We used app.before_ request and app.after_ request in our demonstration code. 
Eventually, you will want objects to stick around in your code between the before- and after- 
request handlers. 


Before and after a request 


If you need to keep an object around between the before and after request hooks, you can 
set an attribute on the flask .g object. The g object only lives for the duration of the request, 
and you can set anything you want on the g object. This is for convenience, for the things that 
you need throughout the request, but do not yet have a home. Do not abuse the g object by 
giving it objects that belong elsewhere, such as a database system. 


Here is the g object in action, where a random integer between O and 9 is set ong. x and 
logged before and after the request: 


import random 
from flask import g 


@app.before_ request 
def set_on_g object(): 
x = random.randint(0, 9) 
app.logger.debug('before request: g.x is {x}'.format (x=x) ) 


g.xX =X 


@app.after_ request 
def get_on_g object (response) : 
app. logger .debug ( 
‘after request: g.x is {g.x}!'.format (g=g) ) 
return response 
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Handling static files (Simple) 


Flask is ready to serve files on your disk from the moment you serve your first request. 


Getting ready 


Go to your scheduler project and look at the static folder inside the sched directory. 


How to do it... 


Put the files inside the static folder. 


2. Build URLs for them using flask.url_for('static', filename='path/to/ 
filename') where path/to/filename is the file path inside the static folder, 
using / regardless of the operating system you are using. 


By convention, Flask looks for a folder named static next to your application, and serves the 
files there at the /static/<path:filename> URL, matching all the files in your static 
folder and its subdirectories. That is, if your application is at app. py, then by default, Flask 
will look at the static folder next to app. py. Placing a file at /static/img/favicon. 

ico next to app. py becomes available at the URL /static/img/favicon.ico, which 
ishttp://localhost:5000/static/img/favicon.ico in the default development 
server. (This favicon is wired up in the next section on templating.) 


You can customize how Flask handles static files. 


Serving static files in production 


When you deploy your application, you will likely want to serve static files from an industrial 
strength HTTP server such as nginx or Apache httpd, which are highly optimized for static 
files. You can configure these servers to serve the /static/ URL from the same /static/ 
folder in your project. If you do not have access to these servers, you can use Flask's static file 
handling in production if you need to. 
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Hosting static files elsewhere 

If you are using static files served by another server at a URL other than /static/, you can 
add routes to your Flask application with the build_on1y option. This tells Flask how to build 
URLs with the flask.url1_for function, without needing a view function or having Flask 
attempt to serve those files. 


app.add_url_rule('/attachments/<path:filename>', 
endpoint='attachments', build_only=True) 


Custom static file handler 

You can build your own static file handler if you need to do any custom handling when serving 
files from the filesystem (for example, only serving a file to users who pay), for use in static 
files outside your static folder (for example, /robots.txt), or to override Flask's built-in 
static view function: 


import os.path 
from flask import Flask, send _ from directory 


# Setting static_folder=None disables built-in static handler. 
app = Flask(_ name, static _folder=None) 

# Use folder called 'assets' sitting next to app.py module. 
assets folder = os.path.join(app.root_path, '‘assets') 


@app.route('/assets/<path:filename>') 
def assets (filename): 
# Add custom handling here. 
# Send a file download response. 
return send_from_directory(assets folder, filename) 


Using a hard-coded directory and send_from_directory will mitigate directory traversal 
attacks, because the underlying implementation uses flask.safe_join (directory, 
filename) to sanitize the input, which you can use in your own code when handling 
filenames passed in as user input. 


Use a custom static view function to do custom handling of static files, and not to change 
configuration of the static folder. If you just need to rename the static folder, use: 


app = Flask(_ name_, static_folder='foldername' ) 


By default, Flask serves static files at /static/ where static is the name of the folder 
provided in the static folder argument, with default static. If you want a different URL 
path from the folder name, use: 


app = Flask(__name_, static_url_path='/assets') 
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HTTP caching 


By default, Flask sends an HTTP header with the static file telling the browser to cache the file 
for 43200 seconds, or 12 hours. You can configure this using the SEND FILE MAX AGE 
DEFAULT configuration variable. For example, if you want aggressive caching on all static files, 
you can set this value to 2592000 seconds, or 30 days: 


app.config['SEND FILE MAX AGE DEFAULT'] = 2592000 


Be careful when increasing the HTTP cache length, because browsers will have stale files 
when you deploy changes. To work around that issue, change the static URL path on redeploy: 


app = Flask(__name_, static_url_path='/static/v2') 


Directory index 


Flask does not list the contents of the files in a static directory for user browsing; you have to 
link to the static files directly. If you need a directory index view, consider using an industrial 
strength static file web server such as nginx or Apache httpd. 


Using a database (Simple) 


Our scheduler application needs data, and we want to store that data properly so that we can 
stop and start our application without losing our appointments. 


Getting ready 


We are working from the models. py file inside the sched directory of our project. 


How to do it... 


SQLAlchemy provides a Python toolkit and object-relational manager for relational databases 
which use SQL. SQLAIchemy stands on its own, regardless of what web framework you use, 
and we can integrate it into Flask with Flask-SQLAIchemy, which will manage database 
connections with the Flask request lifecycle. 


Update requirements.txt: 


Flask 
Flask-Script 
Flask-SQLAlchemy 


Then: 


$ pip install -r requirements.txt 
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Let's model our appointment data structure using SQLAlchemy's declarative extension, which 
allows us to write Python classes to represent database tables. Note that Flask-SQLAlchemy 
includes some declarative functionality, but our application uses pure SQLAlchemy to make 
the code portable to any Python project and to let you reference the core SQLAIchemy docs, 
docs.sqlalchemy.org. 


We are modeling an Appointment class which maps objects to an appointment table. 
Start with a Base class and define an Appointment subclass. SQLAIchemy will find all 
subclasses of Base when working with the underlying database system. We then define 
columns on the Appointment class which will map attributes on every Appointment object 
that we use in our code, storing and retrieving values as columns in the appointment table 
in our database. In models. py: 


from datetime import datetime 


from sqlalchemy import Boolean, Column 

from sqlalchemy import DateTime, Integer, String, Text 
from sqlalchemy.ext.declarative import declarative base 
Base = declarative _base() 


class Appointment (Base) : 
"An appointment on the calendar.""" 
_ tablename_ = ‘appointment’ 


id = Column (Integer, primary _key=True) 
created = Column(DateTime, default=datetime.now) 
modified = Column(DateTime, default=datetime.now, 


onupdate=datetime.now) 


title = Column (String(255) ) 

start = Column(DateTime, nullable=False) 
end = Column(DateTime, nullable=False) 
allday = Column(Boolean, default=False) 
location = Column (String(255) ) 
description = Column (Text) 


To load our domain model in our application, we configure our database on our Flask app and 
setup a db object to get ready for queries in our request handlers, in app. py: 


from flask import Flask 
from flask.ext.sqlalchemy import SQLAlchemy 


from sched.models import Base 
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app = Flask(__name_) 
app.config['SQLALCHEMY DATABASE URI'] = 'sqlite:///sched.db' 


# Use Flask-SQLAlchemy for its engine and session 

# configuration. Load the extension, giving it the app object, 
# and override its default Model class with the pure 

# SQLAlchemy declarative Base class. 

db = SQLAlchemy (app) 

db.Model = Base 


We can add a couple of helpers as methods on the Appointment class. A duration 
property provides a calculation of the length of the appointment, in seconds, using the 
start and end times of the appointment object. The — repr___ method tells Python 
how to represent the appointment object when printing it. This implementation will say 
<Appointment: 1> instead of Python's default form of <_ main .Appointment 
object at 0x26cf2d0>. 


Back in models.py, in the Appointment class declaration, add: 


@property 
def duration(self): 
delta = self.end - self.start 
return delta.days * 24 * 60 * 60 + delta.seconds 


def repr (self): 
return (u'<{self. class. name_}: {self.id}>' 
. format (self=self) ) 


Each Column takes a type, which gives structure to the appointment record. We give 
keyword arguments to Column to define behavior as follows: 


> primary_key: True means that this field is the record identifier. 


>» default: When no data is given, use this value. This can be a function which returns 
a value, for example, set created to the output of datetime .now () to provide the 
date/time at the time the database record is created. 


>» onupdate: When a record is stored or updated, set its value to the return value of 
the given function, for example, set modified to the current date/time at the time 
the database record is updated. 


>» nullable: When False, do not allow records to be stored which do not have a value 
set for this attribute, by raising an exception. 
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The URL sqlite:///sched. db tells SQLAlchemy to use a SQLite database in the current 
working directory. Python ships with support for SQLite, which is an embedded relational 
database management system also available at, sqlite.org. 


We have only modeled our data and told Flask how to connect to a SQLite database. Let's try 
out some queries. 


Querying with SQLAIchemy 


With an Appointment model definition in place, we can run some queries from Python. We 
can make some sample queries before building out our application's view functions. Add the 
following code to the main script of models. py, inside an if name == ' main ' 
block. Add any statements or print calls that you want, in order to see how SQLAIchemy 
works and watch it run with: 


$ python models.py 


<i Where is the web request? This section works with 


~ SQLAlchemy directly, outside a request context, in order to 
illustrate how SQLAIchemy works. This bottom-up approach 
helps you understand your building blocks. 


We start with an engine, which connects to the database and executes queries. If you 

would rather not create a file on disk, you can use a temporary in-memory database. The 
sqlite:// URL tells SQLAlchemy to connect to a SQLite database, and because the filepath 
is omitted, it should connect to a temporary database in memory. That is, the sqlite: // 
URL would provide a database which only exists for the duration of Python's process 
execution, and will not persist across calls to Python. 


from datetime import timedelta 


from sqlalchemy import create engine 
from sqlalchemy.orm import sessionmaker 


engine = create engine('sqlite:///sched.db', echo=True) 


Next we create a session and create the database tables. When the engine connects to 
the database and executes queries, the session represents an on-going conversation with 
the database and is the primary entry point for applications to use a relational database in 
SQLAlIchemy. 


Base.metadata.create_ all (engine) 
Session = sessionmaker (bind=engine) 
session = Session() 
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Now we add some sample data. We generate times for our fake appointments using the 
current time now plus or minus some timedelta, which accepts days and seconds. 


now = datetime.now() 


session.add (Appointment ( 
title='Important Meeting', 
start=now + timedelta(days=3), 
end=now + timedelta(days=3, seconds=3600), 
allday=False, 
location='The Office')) 
session.commit () 


session.add (Appointment ( 
title='Past Meeting', 
start=now - timedelta(days=3), 
end=now - timedelta(days=3, seconds=3600), 
allday=False, 
location='The Office')) 
session.commit () 


session.add (Appointment ( 
title='Follow Up', 
start=now + timedelta(days=4), 
end=now + timedelta(days=4, seconds=3600), 
allday=False, 
location='The Office')) 
session.commit () 


session.add (Appointment ( 
title='Day Off', 
start=now + timedelta(days=5), 
end=now + timedelta(days=5), 
allday=True) ) 

session.commit () 


To create, update, and delete an appointment record: 


# Create. Add a new model instance to the session. 
appt = Appointment ( 
title='My Appointment', 
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start=now, 
end=now + timedelta(seconds=1800), 
allday=False) 


session.add (appt) 
session.commit () 


# Update. Update the object in place, then commit. 
appt.title = 'Your Appointment' 
session.commit () 


# Delete. Tell the session to delete the object. 
session.delete (appt) 


session.commit () 


Here are some sample queries you can run to get an idea of how SQLAIchemy works. Each 
appt example is a Python object of type Appointment. Each appts example is a Python list 
of Appointment objects. 


# Get an appointment by ID. 
appt = session.query (Appointment) .get (1) 


# Get all appointments. 
appts = session.query (Appointment) .all() 


# Get all appointments before right now, after right now. 

appts = session.query (Appointment) .filter(Appointment.start < 
datetime.now()).all() 

appts = session.query (Appointment) .filter(Appointment.start >= 
datetime.now()).all() 


# Get all appointments before a certain date. 
appts = session.query (Appointment) .filter(Appointment.start <= 
datetime (2013, 5, 1)).all() 


# Get the first appointment matching the filter query. 


appt = session.query (Appointment) .filter(Appointment.start <= 
datetime (2013, 5, 1)).first() 


SQLAIchemy provides full SQL functionality. Be sure to refer to the SQLAlchemy docs when you 
are generating SQL queries from your Python code. 
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About the session object: you will be using db. session (on the db 
A object we added to app . py İn this section) instead of session directly. 
Q Flask-SQLAlchemy will make sure that db. session is instantiated 
correctly and that data accessed through the database session in one 
web request does not interfere with the session in other requests. 


Production database 


SQLite is great for development and can work in production, but when you deploy your code, 
you may want to use PostgreSQL or MySQL as your database management system. You 

can change the underlying database while keeping your models as they are by specifying a 
different database URL and installing the necessary package to bind to the database. 


For PostgreSQL: 
>» URL pattern: postgresql: //user:pass@localhost :5432/database_ name 
> pip install psycopg2 
For MySQL: 
>» URL pattern: mysql: //user:pass@localhost :3306/database_ name 
> pip install mysql-python 
Remember to create tables when you connect to a clean database. 


SQLAIchemy knows how to translate data definitions to all major relational database 
management systems, and when you need to use specific database features, it has support 
for SQL dialects as documented at docs.sqlalchemy.org/en/rel_ 0 8/dialects/. 


Naming conventions 


Our Appointment class uses an underlying table named appointment. | recommend 
singular table names with a primary key, always named id, but you can decide for yourself 
how to name your tables and columns. 


Custom SQL 


At its core, SQLAIchemy is a Python toolkit to construct parameterized SQL expressions. At 
any point, if you need to write custom queries, you do not need to drop down to raw execute 
statement by passing strings—SQLAIchemy has the tools for you. 


See the SQL Expression Language docs at docs. sqlalchemy.org/en/rel_0_ 8/core/. 
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Document stores and non-relational databases 


If you prefer another database management system, perhaps one which is document- 
oriented instead of relational, use the tools available for connecting to that database from 
Python. As you can see, we have kept the domain model declarations isolated in one file and 
hooked them into the Flask application object with a few lines of code. Our application code 
throughout this book will use SQLAlchemy APIs to query data, but you can translate these calls 
to the database of your choice. 


Handling forms and file uploads (Simple) 


Let's get data from the user. Before we begin, remember to NEVER trust user input 
because sooner or later Someone (or someone's Script) with malicious intent will try to 
break your application. 


Getting ready 


We are working from the forms . py file inside the sched directory of our project. 


How to do it... 


1. Now that we have a data model, we need to present a form to the user in order to 
fill our database and validate user input to make sure it matches our schema. You 
can validate incoming data using any tools you like. We will use WTForms in our 
scheduler. 


2. Update requirements.txt: 


Flask 
Flask-Script 
Flask-SQLAlchemy 
WTForms 


3. Then: 


$ pip install -r requirements.txt 


4. WTForms models forms with classes in a similar style to SQLAlchemy's declarative 
extension for modeling database tables. It takes the philosophy that forms should be 
modeled separately from the data, such that forms and data are separate concerns 
and often user forms (in the HTML user interface) do not line up exactly with the 
domain data (in the database modeled with SQLAlchemy). WTForms provides HTML 
form generation and validation of form data. In Flask, you will find submitted form 
data in request . form on the POST and PUT requests. 
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5. Here is our appointment's form. Each attribute takes a label and a set of validators. 
The Length (max=255) validator ensures an input of maximum of 255 characters, 
and the required () validator rejects an empty input. In forms. py: 


from wtforms import Form, BooleanField, DateTimeField 
from wtforms import TextAreaField, TextField 
from wtforms.validators import Length, required 


class AppointmentForm(Form) : 
title = TextField('Title', [Length(max=255) ] ) 
start = DateTimeField('Start', [required()]) 
end = DateTimeField('End') 
allday = BooleanField('All Day') 
location = TextField('Location', [Length (max=255)]) 
description = TextAreaField('Description' ) 


The purpose of Appointment Form Class is two-fold: render an input form in HTML and 
validate submitted data. This matches the SQLAlchemy-based Appointment class very 
closely. Where the Appointment model represents the domain and its persistence, this form 
class represents how to display a form in HTML and accept or reject the results. 


Here is an opportunity to see what our code does before adding it to 
A our Flask application, in our bottom-up approach. This section explains 
how WTForms works through some example code. You can add this 
code to the bottom of forms . py inside an if name == ' 
main__' block, and watch it run with python forms .py. 


Before we add the form to our application in a later section, let's see the form in action on 
its own. We will print the values that WTForms creates so that we can understand what it is 
doing. If you are using Python 2, you will need to add a line to the top of your Python file in 
order to make your print expressions compatible between Python 2 and Python 3: 


from future import print_function 
The following code prints the HTML representation of the title field: 


# Demonstration of a WTForms form by itself. 
form = Appointment Form () 

print ('Here is how a form field displays:') 
print (form.title.label) 

print (form.title) 
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Output: 


Here is how a form field displays: 
<label for="title"sTitle</label> 
<input id="title" name="title" type="text" value=""5 


When displayed in the browser, this form field renders as a very plain input as shown in the 
following screenshot. We will style our forms in a later section on HTML templating. 


Title 


The following code shows how to interact with the form's validation directly. You can 
instantiate the Appointment Form with a dictionary of form data. You can give Flask's 
request . form object to Appointment Form, but here we will build our own dictionary to 
see how it works. Since HTML forms support multiple values for a single argument, we cannot 
use Python's built-in dict. Instead we use Werkzeug's ImmutableMultiDict type and 
make dummy data for a title field and omit all of the other fields. 


# Give it some data. 
from werkzeug.datastructures import \ 
ImmutableMultiDict as multidict 


data = multidict([('title', 'Hello, form!')]) 
form = Appointment Form (data) 


print ('Here is validation...') 
print ('Does it validate: {}'.format (form.validate())) 
print ('There is an error attached to the field...') 

( 


print ('form.start.errors: {}'.format (form.start.errors) ) 


Output: 


Here is validation... 

Does it validate: False 

There is an error attached to the field... 
form.start.errors: [u'This field is required.'] 


Notice that when Appointment Form is given the dictionary form data, form. validate () 
will process it and return either True or False depending on whether the form data is 
valid (True means valid). Errors from validators are loaded on each of the fields in an 
errors list so that you can display errors in context, which we will do when rendering a 
template in a later section. 
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We handle file uploads a bit differently. 


Handling file uploads 


If you are handling file uploads, you need to interact with Flask directly. These snippets will get 
you started. First, the HTML form will include these basic elements: enctype=multipart/ 
form-data attribute on the form element and file input in the form of "<input 

type=file name=...>". 


<form method=post enctype=multipart/form-data> 
<input type=file name=file> 
<input type=submit value=Attach> 

</form> 


The code on the receiving end should look for a Werkzeug FileStorage object in the 
request .files dictionary by the name given on the file input element, and then sanitize the 
filename before saving the file to disk. Note that if you serve the file back with a Content-Type in 
the response which matches the filename's extension, you should only do so with file extensions 
you trust. Otherwise, an attacker could use your file-upload feature to embed JavaScript in your 
application, which will cause the user's browser to trust someone else's code. 


import os 


from flask import request 
from werkzeug import secure filename 


# '...' here and below need to be set according to your project. 
# In your configuration, set a root folder for file uploads. 
FILE FOLDER = Casa! 


@app.route('...', methods=['POST'] ) 
def file _attach(): 
# Match name from <input type=file name=file>: 'file'. 
filestorage = request.files['file'] 
# Do not allow '..' in the filename. 
filename = secure filename (filestorage. filename) 
dest = os.path.join(FILE FOLDER, filename) 
filestorage.save (dest) 
return 'Put your response here.' 
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Templating with Jinja - setting a base 


template (Simple) 


Flask ships with the Jinja templating engine to render any text format you need. Our scheduler 
will present HTML5 pages rendered by Jinja with a little style and a bit of JavaScript. 


Getting ready 


We will build templates using HTML, CSS, and JavaScript. You will need some familiarity 

with these to understand the responses we build in Flask. We will use Twitter's Bootstrap 
(getbootstrap.com/2.3.2/) framework for CSS and the jQuery (j query. com) library for 
JavaScript. Both include online documentation. Bootstrap also includes icons, which we can 
use in our application, provided by Glyphicons (glyphicons.com). We will use a free theme 
for Bootstrap from Bootswatch (boot swatch. com). 


We are working from base.html1 inside the templates directory within the sched directory. 


This text shows templating by example. In our bottom-up 
a approach, we will start with a base page structure before building 
Q out our specific application pages. Jinja has documentation on all 
of its template features. Be sure to refer to the docs at http: // 
jinja.pocoo.org/docs/ to check out what Jinja provides. 


How to do it... 


We will use public content delivery networks (CDNs) for Bootstrap and jQuery, which will 
speed up our start time in our project. NetDNA provides a public CDN for Bootstrap. The 
jQuery project provides a CDN through MediaTemple. Whenever you are ready or prefer 
to move away from a CDN, simply download the files you need and serve them with your 
application's static files, updating the links in the base template. The CDN URLs are, for 
use in the base template (where ... thing ... identifiers are): 


>» http://netdna.bootstrapcdn.com/bootswatch/2.3.2/united/ 
bootstrap.min.css 


>» http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.2/css/ 
bootstrap-responsive.min.css 


>» http://code.jquery.com/jquery-1.9.1.min.js 


>» http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.2/js/ 
bootstrap.min.js 
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Jinja supports template inheritance, where template files can extend an existing template. 
We will use this feature to layout our base structure, using the block template tag to 
indicate sections which child templates will fill. We provide a block to set the page title, add 
any additional content to the page head (which is useful for additional style and scripting), 
and fill the main content of the page. Jinja uses template tags {% ... %} to indicate Jinja- 
specific markup and directives. Here is our base template, in templates/base.htm1, with 
screenshots in the coming sections: 


<!DOCTYPE html> 

<html lang="en"> 

<head> 
<title>{% block title %}{% endblock title %}</title> 
<link rel="shortcut icon" type="image/x-icon" 


href="{{ url_for('static', filename='img/favicon.ico') }}"/> 
<link href="... bootstrap css ..." rel="stylesheet"> 
<link href="... responsive css ..." rel="stylesheet" > 
<script src="... jQuery js ..."></script> 
<script src="... bootstrap js ..."></script> 
{# Link any other .css or .js found in app static folder. #} 
<style> 

{# Add simple CSS style tweaks here. #} 
</style> 
<script> 

$(function() { 


{# Add page-load JavaScript here. #} 


D; 


</script> 

{% block extra_head %}{% endblock extra_head %} 
</head> 
<body> 


<div id="main"> 
<div class="utility-nav navbar navbar-fixed-top"> 
<div class="navbar-inner"> 
<div class="container"> 
{# Navbar goes here. #} 
</div> 
</div> 
</div> 
<div class="content container"> 
{% block main %}{% endblock main %} 
</div> 
</div> 
</body> 
</html> 
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This base template allows us to write focused pages which share a common structure and 
style. Any template you create in the templates directory can inherit the base: 


o 


extends 'base.html' %} 
block title %}Page Title{% endblock title %} 
block main %} 
<h2>This is a child template.</h2> 
{% endblock main %} 


~ 
œ Æ Æ 


Render it with the flask. render_template function. If the file is named index.html 
inside the templates directory, you can render that template into a string with: 


from flask import render template 
Fore 
@app.route('/') 
def index() : 
return render_template('index.html1') 


Ther's a lot more that can be done using Jinja templating 


Using a template engine other than Jinja 


You can choose any template engine you like. When you call render_template, you have a 
Python string, and Flask converts the string into a Response object. If you prefer a different 
approach to templating, build a string and return it from your view functions. Flask bundles 
Jinja to provide a default templating environment for quick start, and for the community to 
build Flask extensions which are guaranteed a common environment. 


Manage web packages with Bower 


You can manage downloaded static files using Bower, a package manager for web tools, 
bower. io. With Bower, you would list dependencies using a bower . json file, use bower 
install to load these files, and then serve the files in your application's static area. 
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Creating a new record (Intermediate) 


Here we provide a web form to create a new appointment as shown in the following screenshot: 


[T] Add Appointment 


[D localhost :5000/appointments/create, 


sched My Appointments Create an Appointment ron@example.com + 


Add Appointment 
Title 
Start 


End 


All Day 


Location 


Description 


Save or Cancel 


Getting ready 


We will continue to work from the app. py file from sched and the templates directory. 
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How to do it... 


1. We provide a view function to do both GET and POST handling for the form. Here, we 
pull together db . session from the database section and Appointment Form from 
the forms section. In app. py: 


from flask import abort, jsonify, redirect, render template 
from flask import request, url for 

from sched.forms import AppointmentForm 

from sched.models import Appointment 


# ... skipping ahead. Keep previous code from app.py here. 


@app.route('/appointments/create/', methods=['GET!', 'POST']) 
def appointment _create(): 
"""Brovide HTML form to create a new appointment.""" 
form = Appointment Form (request. form) 
if request.method == 'POST' and form.validate(): 
appt = Appointment () 
form.populate_obj (appt) 
db.session.add (appt) 
db.session.commit () 
# Success. Send user back to full appointment list. 
return redirect (url _for('appointment_list') ) 
# Either first load or validation error at this point. 
return render_template('appointment/edit.html', 
form=form) 

2. Before we build out the input fields, we can create a utility for ourselves which will 
display all of the WTForms features for a given field: label, input, and errors. Jinja has 
macros, which are similar to Python functions. We will create a macro to render an 
edit field from Appointment Form. 


3. For inputs, we can follow Bootstrap conventions with control-group and 
controls page elements, which will let us completely control the form flow from 
CSS. We want to start a new template with our macro, so that we can reuse it in other 
templates we create. In templates/appointment/common. html: 


o 


{% macro edit_field(field, catch_kwargs=true) %} 
<div class="control-group{% if field.errors %} error{% endif 
}"> 
{{ field.label(class="control-label") }} 
<div class="controls"> 
{{ field(**kwargs) }} 
{% for error in field.errors %} 
<span class="help-inline">{{ error }}</span> 
{% endfor %} 
</div> 
</div> 
{% endmacro %} 
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Now we can build a form using our new macro. Starting a new template, we can 
extend the base and import the macro. When extending the base, we provide blocks 
title and main, using the same syntax as the base template. You can set variables 
within a template, for use within that template, using { set ... %}. 


In templates/appointment/edit.html: 


{% extends 'base.html' %} 
{% from 'appointment/common.html' import edit field %} 
{% set title = 'Add Appointment! %} 


{% block title %}{{ title }}{% endblock title %} 
{% block main %} 
<div class="row"> 
<div class="appointment-edit well offset2 span8"> 
<form method="post" class="form-horizontal"> 
<legend>{{ title }}</legend> 
{{ edit _field(form.title, maxlength=255, class="span3", 
placeholder="Important Meeting") }} 
{{ edit _field(form.start, class="span3", 
type="datetime", 
placeholder="yyyy-mm-dd hh:mm:ss") }} 
{{ edit _field(form.end, class="span3", type="datetime", 
placeholder="yyyy-mm-dd hh:mm:ss") }} 
{{ edit _field(form.allday) }} 
{{ edit _field(form.location, maxlength=255, 
class="sSpan3", 
placeholder="The Office") }} 
{{ edit _field(form.description, rows="5", 
class="sSpan5", 


placeholder="Bring a sharpened #2 pencil.") }} 
<div class="form-actions"> 
<button type="submit" class="btn">Save</button> 


or <a href="{{ url_for('appointment_list') 
}}">cancel</a> 


</div> 
</form> 
</div> 
</div> 
{% endblock main %} 
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On GET, the form is rendered with an action to POST the data to the same URL. On POST, the 
view function validates the data and adds it to the database. If the validation fails, the POST 
renders the template again, but this time the form object has errors. 


Jinja uses template syntax {{ ... }} to print a Python object in context to the template's 
output. We use a simple if statement to add the error class if the field has errors, which 
will highlight the input when errors exist (thanks to Bootstrap style). We use a for loop to 
lay down a help span for each error on the field. The use of **kwargs will catch all 
arguments which are given beyond the macro's call signature; this lets us pass in all 
WTForm field options through the macro. The kwargs feature only works in Jinja macros 
when catch _kwargs=true. 


CSS classes form-horizontal, span3, and span5 tell Bootstrap how to layout the form 
on its grid system. The placeholder attribute is a feature in HTML5 to show a watermark 
in the input when there is no content. 


Displaying a record (Intermediate) 


With content going into the database, let's get it back out as shown in the following figure: 


[1] Important Meeting or x 


LJ localhost :5000 appointments/1 


sched My Appointments Create an Appointment ron@example.com ~ 


Important Meeting 


ft The Office 


æ 2013-04-16 - Tuesday at 10:00am for 2 hours 


f Edit f Delete 


Discuss a lot of important things. The entire team will be there. Be sure to wear your 
lucky shirt. 


Bring the report on last quarter's performance. 
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Getting ready 


We will continue to work from the app. py file from the sched folder and the 
templates directory. 


How to do it... 


1. We provide a simple query to get an appointment by database ID. In app. py: 


# Note the import statements from the previous section. 


@app.route('/appointments/<int:appointment_id>/') 
def appointment _detail (appointment_id): 
"""Brovide HTML page with a given appointment.""" 
# Query: get Appointment object by ID. 
appt = db.session. query (Appointment) .get (appointment_id) 
if appt is None: 
# Abort with Not Found. 
abort (404) 
return render_template('appointment/detail.html', 


appt=appt) 


2. Let's take the same macro approach to displaying an appointment. A template macro 
will give us a tool to display an appointment any time we need it. In templates/ 
appointment/common.htmL1: 


{% macro detail (appt, 
link title=false, 
show_edit=true, 
show_description=true) %} 
<div class="appointment-detail"> 
{% if link title %} 
<h3> 
<a href="{{ url_for('appointment_detail', 
appointment _id=appt.id) }}"> 
{{ appt.title }}</a> 
</h3> 
{% else %} 
<h3>{{ appt.title }}</h3> 
{% endif %} 
{% if appt.location %} 
<p><i class="icon-home"></i> {{ appt.location }}</p> 
{% endif %} 
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{% if appt.allday %} 
<p><i class="icon-calendar"></i> {{ appt.start | date 
}}</p> 
{% else %} 
<p><i class="icon-calendar"></i> {{ appt.start | 
datetime }} 
for {{ appt.duration | duration }}</p> 
{% endif %} 
{% if show edit %} 
<div class="edit-controls"> 
<i class="icon-pencil"></i> 
<a href="{{ url_for('appointment_edit', 
appointment id=appt.id) }}">Edit</a> 
<span class="inline-pad"></span> 
<i class="icon-trash"></i> 
<a class="appointment-delete-link" href="#" 
data-delete-url="{{ url_for('appointment delete’, 
appointment _id=appt.id) }}">Delete</a> 
</div> 
{% endif %} 
{% if show description and appt.description %} 
<div class="row"> 


<p class="span5">{{ appt.description | nl2br }}</p> 


</div> 
{% endif %} 
</div> 


{% endmacro %} 


3. We can then use the macro in templates/appointment/detail.html: 


{% extends 'base.html' %} 


{% from 'appointment/common.html' import detail %} 


{% block title %} 


{{ appt.title }} 
{% endblock title %} 


{% block main %} 
<div class="row"> 
<div class="spanl2"> 
{{ detail(appt) }} 
</div> 
</div> 
{% endblock main %} 
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If a request comes in for a database ID that does not exist, we tell Flask to abort with a 404 
Not Found response. The flask. abort function is implemented as an exception, so Python 
will stop execution in the current function when abort is called. 


We will also implement a few utilities for Jinja named filters, which formats the output of a 
Python object before it goes into the template's output, in the form of {{ foo | filter }}. 
We will build filters date, datetime, duration, and nl2br. On your first pass through in 
implementing these, simply omit these from your template; use {{ appt.start }} instead of 
{{ appt.start | date }}. This will give you a clearer idea of why we are building the filter. 


For individual fields which may not exist, we use Python's or behavior. When used for display 
or assignment, or expression is "shortcut" until a true value is hit, and that value is used. This 
approach lets us provide a default display value in a simple way. 


Editing a record (Intermediate) 
Now we provide an edit page for existing appointments, as shown in the following screenshot: 


[T] Edit Appointment 


D localhost :5000/appointments/1/edit. 


sched My Appointments Create an Appointment ron@example.com ~ 


Edit Appointment 
Title Important Meeting 
Start 2013-04-16 10:00:00 
End 2013-04-16 12:00:00 
All Day 
Location _ The Office 


Description Discuss alot of important things. The entire team 
will be there. Be sure to wear your lucky shirt. 


Bring the report on last quarter's performance. 


Save or Cancel 
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Getting ready 


We will continue to work from the app. py file from the sched directory and 
templates directory. 


How to do it... 


1. The edit workflow is a mix of add and detail views. We get an appointment, and if it 
exists, we display a form to edit it. In app. py: 


@app.route('/appointments/ 
<int:appointment_id>/edit/, 
methods=['GET', 'POST']) 


def appointment _edit (appointment_id) : 
"""Brovide HTML form to edit a given appointment.""" 
appt = db.session. query (Appointment) .get (appointment_id) 
if appt is None: 
abort (404) 
form = AppointmentForm(request.form, appt) 
if request.method == 'POST' and form.validate(): 
form.populate_obj (appt) 
db.session.commit () 
# Success. Send the user back to the detail view. 
return redirect (url_for('appointment_detail', 
appointment _id=appt.id) ) 
return render_template('appointment/edit.html', 
form=form) 


2. Intemplates/appointment/edit.htmlL: 


{% if request.endpoint.endswith('edit') %} 


{% set title = 'Edit Appointment' %} 
{% else %} 
{% set title = 'Add Appointment' %} 


{% endif %} 


We reuse the same template as the create form, but we say Edit instead of Add. Since this 
is very simple logic, we can use an if statement in the template. Flask lets us inspect the 
request object in the template. If you find your project does a lot of request inspection, you 
should consider a design pattern which moves this logic back into your Python code. 
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Listing all records (Simple) 


We don't want users to keep track of the database IDs of their appointments, so we provide a 
view, which will list all the appointments that they have, as shown in the following screenshot: 


[T] Appointments 


[D localhost:5000 


sched My Appointments Create an Appointment ron@example.com ~ 


Important Meeting 


ft The Office 
& 2013-04-16 - Tuesday at 10:00am for 2 hours 


Follow Up 


ft The Office 


@ 2013-04-17 - Wednesday at 11:00am for 1 hour 


Day Off 


& 2013-04-20 - Saturday 


Getting ready 


We will continue to work from the app. py file from the sched directory and the 
templates directory. 


How to do it... 


1. We query for all appointments, in app. py: 


@app.route('/appointments/') 
def appointment _list(): 
"""Brovide HTML listing of all appointments.""" 
# Query: Get all Appointment objects, sorted by date. 
appts = (db.session. query (Appointment) 
.order_ by (Appointment.start.asc()).all()) 
return render_template('appointment/index.html', 
appts=appts) 
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2. Intemplates/appointment /index.html: 


{% extends 'base.html' %} 
{% from 'appointment/common.html' import detail %} 
{% block title %}Appointments{% endblock title %} 


{% block main %} 
<div class="row"> 
{% for appt in appts %} 
<div class="spanl2"> 
{{ detail(appt, 
link title=true, 
show_edit=false, 
show _description=false) }} 
</div> 
{% else %} 
<h3 class="spanl2">No appointments.</h3> 
{% endfor %} 
</div> 
{% endblock main %} 


We query for all appointments in ascending order by appointment start time. SQLAlchemy 
declarative classes include helpers on column attributes that let us provide SQL clauses, 
here with .asc() to indicate the sort field. In the appointment list template, we iterate over 
all appointment records and reuse our display macro and switch off the features which only 
apply to the detail view, using the call signature we created. 


We kept the appointment list simple. If you are new to database identifiers, you may be 
wondering how the appointment URLs are generated. 


Database identifiers 


A note on those database IDs: they are system generated by our database management 
system and SQLAIchemy. That is, they are meaningless outside of our application. IDs make 
for good URLs, but not for human memory. This view is one where you can get creative and 
use the day, week, month, and year calendar metaphors. You can do that, but that will live 
mostly in HTML, CSS, and JavaScript. For our simple scheduler application, we just list out the 
appointments in a list. 
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Deleting a record (Advanced) 


We are all set with our appointment interactions. Wait; how do we delete appointments? 


Getting ready 


We will continue to work from sched's app. py file and templates directory. 


How to do it... 


1. We build an Ajax handler, in app. py: 


@app.route('/appointments/ 
<int:appointment_id>/delete/', 
methods=['DELETE'] ) 


def appointment delete (appointment_id): 

"""Delete record using HTTP DELETE, respond with JSON.""" 

appt = db.session. query (Appointment) .get (appointment_id) 

if appt is None: 
# Abort with Not Found, but with simple JSON response. 
response = jsonify({'status': 'Not Found'}) 
response.status = 404 
return response 

db.session.delete (appt) 

db.session.commit () 

return jsonify({'status': 'OK'}) 


2. A little jQuery will wire up all delete links to use this handler, in templates/base. 
html: 


<script> 
$(function() { 
$(".appointment-delete-link").on("click", function () { 
var delete_url = $(this) .attr('data-delete-url'); 
$.ajax({ 
url: delete_url, 
type: 'DELETE', 
success: function (response) { 
== 'OK') { 
window.location = {{ url_for('appointment_list') 
}}; 
} else { 
alert ('Delete failed.') 


if (response.status 
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} 
pD; 
return false; 
DE 
DE 


</script> 


We provide our first view function which does not render HTML, but uses a minimal Ajax 
interacting with JSON. It accepts HTTP DELETE requests and does the work. We do not have 

to expose delete functionality through GET requests, which would let users accidentally delete 
database records by browsing. This is particularly important when we publish code which can 
be hit by search engines and other robots. Crawling all of our pages would delete our entire 
database! Flask provides a j sonify function to turn a Python dictionary into a JSON response. 


How do you get a browser to send a DELETE request? With JavaScript. The jQuery library 
makes Ajax calls a lot simpler than JavaScript alone. We add a jQuery hook which will take 
all delete links and submit an ajax call when they are clicked. The on-click callback grabs the 
deletion URL from the delete link, and sends it as a DELETE request. On success, it redirects 
the current browser window to the appointment list. By placing this script into the base 
template, it will make all delete links functional on the appointment list and detail pages. 


We only cover Ajax briefly here; it deserves an entire book. 


Ajax 

Ajax simply means that we render a web page and have the browser communicate with our 
web service without necessarily having to reload the page. That is, render the page once, 

and update the content displayed on the page without refreshing the entire page. This was 
originally called AJAX for "asynchronous JavaScript and XML", but has become a common word 
among web developers and can mean any serialization format, here JSON instead of XML. 


Using custom template filters in Jinja 


(Advanced) 


To wrap up our templates, we need to clean up the display of some of our fields. 


Getting ready 


We move to the filters .py file from the sched directory and work with app. py again. 
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How to do it... 


1. We want to display time with a clean format. In filters.py: 


def do datetime (dt, format=None) : 
"""Jinja template filter to format a datetime object.""" 
if dt is None: 
# By default, render an empty string. 
return "I 
if format is None: 
# No format is given in the template call. 
# Use a default format. 
# 
# Format time in its own strftime call in order to: 
# 1. Left-strip leading 0 in hour display. 
# 2. Use 'am'/'pm' (lower case) instead of 'AM'/'PM'. 
formatted date = dt.strftime('sY-%m-%d - %A') 
formatted time =\ 
dt.strftime('%I:3M%p') .lstrip('0') . lower () 
formatted = '%s at %s' %\ 
(formatted_date, formatted_time) 
else: 
formatted = dt.strftime (format) 
return formatted 


2. Add more filters here, and provide a hook to initialize the Flask application. 
def init _app(app): 
"""Tnitialize a Flask application with custom filters.""" 
app.jinja_env.filters['datetime'] = do datetime 


3. Use the initialization hook in app. py: 


from sched import filters 
filters.init_app (app) 


Jinja supports an environment where Python functions are provided in the template as filters. 
We have a datetime field on our appointment, so we provide some formatting for it. You can 
call attributes and methods directly within the template, {{ dt.strftime('%Y-%m-%d') 
}}, but defining a filter lets us specify how to format all dates centrally while still exposing 
parameters. You can call {{ dt | datetime }} with our datetime filter to get the default 
functionality that we defined, as wellas {{ dt | datetime('%y-%m-%d') }} where the 
argument in the template call is passed in as an argument after the value being filtered. 


[54] 
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You can find the full code for filters in the source code files downloadable on the Packt website. 


Additional filters 


The full source code of sched includes filters for default date formatting, duration formatting 
for the appointment records, and the n12br filter to preserve user-entered line breaks in the 
appointment description field (Since HTML normalizes whitespace otherwise). 


Sending error responses (Simple) 


In this section, we will Send an error page to the user with style. 


Getting ready 


We are working from the app. py file inside the sched directory of our project, and in 
the templates directory inside sched. Create a directory named error inside the 
templates directory. 


How to do it... 


1. When the user hits a Not Found page, we want to display a page that will direct them 
back to the appointment list. You can tell Flask how to render responses for error 
cases, typically for HTTP error codes. We will provide a custom 404 Not Found page 
as shown in the following screenshot: 


[J Not Found 


G | D localhost:so00/appointments/10 


sched My Appointments Create an Appointment ron@example.com ~ 
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2. Flask provides app .errorhandler to tell Flask how to handle certain kinds of 
errors, taking either 4xx or 5xx HTTP status codes or Python exception classes. 
Decorate a function which accepts an Exception instance and returns a response. 
Be sure to include the HTTP status code in the Flask response, by providing 404 ina 
tuple response with the rendered template string. In the following code, we render a 
not-found template, which provides a link back to the appointment list. In app. py: 


@app.errorhandler (404) 
def error_not_found(error) : 
return render_template('error/not_found.html'), 404 


3. Intemplates/error/not_found.html: 


{% extends 'base.html' %} 
{% block title %}Not Found{% endblock title %} 


{% block main %} 
<h2>sNot Found</h2> 
{% endblock main %} 


The navbar element in the base template will help users navigate back to a known page. 


The app.errorhandler decorator accepts exception classes or HTTP status codes as 
integers. Following are some HTTP status codes to get you started. You can use these with 
flask.abort (status_code) in your view functions to jump directly to an error response, 
and define a custom app. errorhand1er to provide a styled response. 

>» 400 Bad Request 

>» 401 Unauthorized 

>» 403 Forbidden 

>» 404 Not Found 

>» 405 Method Not Allowed (you may have forgotten methods in your route) 

>» 410 Gone (and not coming back) 

>» 500 Internal Server Error 


See www.w3 .org/Protocols/rfc2616/rf£c2616-sec10.html for the full list. 


The 500 error handler will display anytime your code has an uncaught exception. 
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Flask provides a very useful debugger to inspect your errors in development. 


Handling specific exceptions 
You can provide a custom error page on Python exceptions: 


class SchedulingException (Exception) : 
"""Some application-specific error has occurred.""" 
pass 


@app.errorhandler (SchedulingException) 
def scheduling exception_handler (error): 
return 'Just a demo of app.errorhandler...', 500 


@app.route('/test_error/') 
def test_error(): 
raise SchedulingException('Use my custom error handler.') 


Flask’s debugger 

This is a good place to discuss Flask's debugger. When a Flask application has app. 
config['DEBUG'] set to True, any uncaught exception in the application code will display 
a developer-friendly debugger in the browser. This debugger makes the Python stack trace 
interactive, letting you run code at any point in the stack frame and viewing code in context. 


In app. py: 


app = Flask(__name_) 
app.config['DEBUG'] = True 


You can trigger exceptions intentionally for a quick peek at your stack. Write in an exception 
and hit the route in your web browser. My two favorite exceptions are: 


1/0 # Divide by zero to get an exception. 
raise Exception("Don't Panic!") 


Only use this in development on a secured machine, since the interactive interpreter 

allows execution of Python code from the browser. If the interactive interpreter becomes 
unresponsive in the browser, either the development server has shut down or has moved on 
to new requests, forgetting about your error. 
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Authenticating users (Advanced) 


So far we have assumed that anyone who can access the sched application should be 
able to create, display, edit, list, and delete appointment records in the database. Our Flask 
application needs to authenticate users and protect our database. 


Getting ready 


We return to the models. py file inside the sched directory of our project. 


How to do it... 


1. We start with a database record for the user with a unique e-mail address, in 
models .py: 


from datetime import datetime 


from sqlalchemy import Column 

from sqlalchemy import Boolean, DateTime, Integer, String 
from sqlalchemy.orm import synonym 

from sqlalchemy.ext.declarative import declarative base 
from werkzeug import check password_hash 

from werkzeug import generate password hash 


Base = declarative_base() 


class User (Base): 
"""A user login, with credentials and authentication.""" 
__tablename__ = 'user' 


id = Column (Integer, primary _key=True) 

created = Column(DateTime, default=datetime.now) 

modified = Column(DateTime, default=datetime.now, 
onupdate=datetime.now) 


name = Column('name', String(200) ) 
email = Column(String(100), unique=True, nullable=False) 
active = Column(Boolean, default=True) 
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2. Then, we add a means to store a password hash (continuing in User definition): 


_password = Column('password', String(100) ) 


def _get_password (self): 
return self. password 


def _set_password(self, password): 
if password: 
password = password.strip() 
self. password = generate_password_hash (password) 


password descriptor = property(_get_ password, 
_set_password) 

password = synonym(' password', 
descriptor=password descriptor) 


3. Finally, we add a means to validate a password (continuing in User definition): 


def check password(self, password): 
if self.password is None: 
return False 
password = password.strip() 
if not password: 
return False 
return check password _hash(self.password, password) 


@classmethod 
def authenticate(cls, query, email, password): 
email = email.strip().lower() 
user = query(cls) .filter(cls.email==email) .first() 
if user is None: 
return None, False 
if not user.active: 
return user, False 
return user, user.check password (password) 
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We need a place to store user records, so that we can verify whether an authentication 
request is for a valid user in our application. However, we do not want to store the password in 
clear text, which would let anyone with read access to the database table know how to login 
as a valid user in the application. This may not seem important the first time you come across 
the idea, but you do not want to handle the responsibility of storing everyone's passwords, 
especially if users reuse passwords across applications. (This should be a hint as to why that 
is a bad idea.) 


Werkzeug provides utilities to hash a password and verify that the provided password matches 
that hash. We store the hash and not the clear-text password. Anytime user . password is 
set on a User instance, the password is immediately hashed using a Python descriptor and 
SQLAIchemy's synonym hook. The synonym lets us have user . password behave just like 
every other SQLAlchemy object attribute, but when user . password is accessed, getting the 
value will call get password and setting it will call set password, which will store a 
hashed value. 


We can now authenticate using e-mail, password, and a SQLAIchemy query object with 
User.authenticate (query, email, password), which returns a user, bool pair 
(tuple), where user is the matching user object and the Boolean value indicates whether the 
authentication is valid. 


We need to integrate our e-mail/password authentication into our application. 


Appointment relationship 


We can build a relationship between appointments and users so that we display only the 
current user's appointments when we load schedules. Update the Appointment Class in 
models. py to include a foreign-key relationship to User: 


class Appointment (Base) : 
# ... existing code. 
user_id = Column(Integer, 
Foreignkey('user.id'), nullable=False) 
user = relationship (User, lazy='joined', join _depth=1) 
# ... existing code. 


Accessing an Appointment object will now provide the appointment .user 
property to access the User object for the owner of that appointment. Because we 
used ForeignKey, SQLAIchemy knows how to fetch the related User record when 
accessing an Appointment object. 
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Opening a session 

HTTP is stateless, meaning that one request has no information about the previous 
requests. We need to open a session that is retained from request-to-request, so that we can 
authenticate the user in one request and use that authentication in each of the following 
requests that the user makes in a given sitting. 


In the next section, we will see how to handle the session, adding a current_user object 
to our code which will represent the User database object which matches the currently 
authenticated user. Now that we've added a relationship between User and Appointment 
in models.py, we need to update app. py for every case where we create or retrieve an 
Appointment object. Change the Appointment object creation line to: 


appt = Appointment (user_id=current_user.id) 
Then verify whether the current Appointment is for the current User when retrieving records: 


if appt.user_id != current_user.id: 
abort (403) 


Database migration 


Changing models. py means that we need to update the database structure of the database 
we have been using in development, or the production database if we have already deployed 
the sched application. If the only changes we have made are to add tables, then we can 
simply make another call to Base.metadata.create_all (engine). 


Sometimes in development, this is the easiest method: just destroy the development 
database, run create_al1 again, then start adding data again. Setting up initial 
development or test data can be cumbersome, so you might want to invest in fixtures, which 
you load before running your application development server. There are several projects in the 
Python community to do this, including fixture at pypi.python.org/pypi/fixture. 


For column changes, we need to provide an automation to change the live database, 
especially for production databases, which people are using. If you are familiar with SQL, you 
can write your own ALTER TABLE statements and provide your own scripts. If you would like 
a toolkit to manage this, SQLAlchemy's creator Mike Bayer has written Alembic as a tool to 
perform migrations in SQLAlchemy, alembic.readthedocs.org. 


Authenticating with existing services 


How do new users get started? With user authentication in place for sched, you need to 
provide a means to register users with your application. This can be as simple as creating 
User objects from the Python interactive interpreter, or it could be a user signup form within 
your application. 
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Alternatively, you can reduce the User implementation to the core application data that you 
need and use an existing service to authenticate your users externally, creating new User 
objects on the first such authentication. This will keep users from having to remember yet 
another password and speed up your user acquisition process. 


OpenID (openid.net) provides an open standard to perform this style of authentication. 
Popular services such as Google have their own documentation for authentication and 
authorization using existing user accounts, developers.google.com/accounts/. 


Handling sessions and users (Intermediate) 


Since HTTP is stateless, we need to track some data across requests with a session. 


Getting ready 


We will continue to work from the app. py file from the sched directory and the 
models.py file. 


How to do it... 


1. Flask provides a session object, which behaves like a Python dictionary, and 
persists automatically across requests. You can, in your Flask application code: 


from flask import session 


# ... in a request ... 
session['spam'] = 'eggs' 
# ... in another request ... 


spam = session.get('spam') # 'eggs' 


2. Flask-Login provides a simple means to track a user in Flask's session. Update 
requirements.txt: 
Flask 
Flask-Login 
Flask-Script 
Flask-SQLAl1lchemy 
WTForms 


3. Then: 


$ pip install -r requirements.txt 
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4. Wecan then load Flask-Login into sched's request handling, in app. py: 


from flask.ext.login import LoginManager, current_user 
from flask.ext.login import login_user, logout_user 
from sched.models import User 


# Use Flask-Login to track current user in Flask's session. 
login _manager = LoginManager () 

login _manager.setup_app (app) 

login _manager.login view = 'login' 


@login_manager.user_loader 

def load_user(user_id): 
"""Flask-Login hook to load a User instance from ID.""" 
return db.session. query (User) .get (user_id) 


5. Flask-Login requires four methods on the User object, inside class User in 
models . py: 


def get_id(self): 
return str(self.id) 


def is_active (self): 
return True 


def is_anonymous (self): 
return False 


def is_authenticated (self): 
return True 


1 
Q Flask-Login provides a UserMixin (flask.ext .login.UserMixin) if 


you prefer to use its default implementation. 


6. We then provide routes to log the user in when authenticated and log out. In app. py: 
@app.route('/login/', methods=['GET', 'POST']) 
def login(): 
if current_user.is authenticated (): 
return redirect (url _for('appointment_list') ) 
form = LoginForm(request . form) 
error = None 
if request.method == 'POST' and form.validate(): 
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email = form.username.data.lower().strip() 
password = form.password.data.lower().strip() 
user, authenticated = \ 
User.authenticate(db.session.query, email, 
password) 
if authenticated: 
login_user (user) 
return redirect (url _for('appointment_list') ) 
else: 
error = 'Incorrect username or password. ' 
return render_template('user/login.html', 
form=form, error=error) 


@app.route('/logout/') 
def logout (): 
logout_user () 
return redirect (url for('login') ) 


7. We then decorate every view function that requires a valid user, in app. py: 


from flask.ext.login import login required 
@app.route('/appointments/') 
@login_required 
def appointment _list(): 

# 


On login_user, Flask-Login gets the user object's ID from User. get_idand stores it in 
Flask's session. Flask-Login then sets a before _request handler to load the user instance 
into the current_user object, using the load_user hook we provide. The logout_user 
function then removes the relevant bits from the session. 


If no user is logged in, then current_user will provide an anonymous user object which 
results in current_user.is anonymous () returning True and current_user. 

is authenticated () returning False, which allows application and template code to 
base logic on whether the user is valid. (Flask-Login puts current_user into all template 
contexts.) You can use User.is_ active to make user accounts invalid without actually 
deleting them, by returning False as appropriate. 


View functions decorated with login _required will redirect the user to the login view if the 
current user is not authenticated, without calling the decorated function. 


www.it-ebooks.info 


Instant Flask Web Development 


Flask's session supports display of messages and protection against request forgery. 


Flashing messages 


When you want to display a simple message to indicate a successful operation or a failure 
quickly, you can use Flask's flash messaging, which loads the message into the session until it 
is retrieved. In application code, inside request handling code: 


from flask import flash 
flash('Sucessfully did that thing.', 'success') 
In template code, where you can use the 'success' category for conditional display: 


{% for cat, m in get flashed messages (with _categories=true) %} 
<div class="alert">{{ m }}</div> 
{% endfor %} 


Cross-site request forgery protection 


Malicious web code will attempt to forge data-altering requests for other web services. To 
protect against forgery, you can load a randomized token into the session and into the HTML 
form, and reject the request when the two do not match. This is provided in the Flask-SeaSurf 
extension, pythonhosted.org/Flask-SeaSurf/ or the Flask-WTF extension (which 
integrates WTForms), pythonhosted.org/Flask-ETF/. 


Deploying to the world (Advanced) 


Once satisfied with your application, you can deploy your application which would be available 
to the world. 


Getting ready 


You need a computer which is online and accessible to your target users. Install Python and 
place requirements .txt in a folder where you have command-line access, just as we did 
for your development environment (virtualenv is production-appropriate), then create your 
database tables. You can deploy to any operating system: Windows and any Unix-like systems 
(including Mac OS X). 
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How to do it... 


1. From a clean Ubuntu 12.04 server installation: 
$ sudo apt-get update && sudo apt-get install nginx 
$ # Load config into /etc/nginx/sites-available/default 
$ sudo service nginx restart 
$ pip install gunicorn 


$ gunicorn --access-logfile - -b 127.0.0.1:5000 sched.app:app 


2. Use the pip and gunicorn programs in virtualenv. Load into the nginx configuration, 
changing localhost to your domain name if you have one: 


server { 
listen 80; 
server name localhost; 
access log /var/log/nginx/access.log; 
error_log /var/log/nginx/error.log; 
location / { 
proxy_pass http://127.0.0.1:5000/; 
proxy redirect off; 
proxy set header Host Shost; 
proxy _set_header X-Real-IP Sremote_addr; 


proxy _set_header X-Forwarded-For Sproxy_add_x forwarded_for; 


} 


3. Then add the gunicorn process into the server's boot order instead of running it by 
hand. See your operating system's documentation. For Unix-like systems, supervisord 
provides management of long-running applications, supervisord.org. 


Anytime nginx receives a matching request, it sends a proxy request to the HTTP server 
running on port 5000, which is gunicorn in our application, and passes along the response. 
Note that gunicorn does not automatically reload your application on code updates. You can 
reload with process signals as described in docs.gunicorn.org/en/latest/faq.html. 


See docs.gunicorn.org/en/latest/deploy.html for additional documentation. 
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Deployment has many options; the configuration is entirely up to your project. 


Handling static files with nginx 


Flask provides a static file handler for convenience. Now that we have an optimized HTTP 
server in place, we can have it serve static files directly. The following configuration block 
shows how to serve static files with nginx and proxy all other requests to Flask. Adjust the 
configuration according to your setup: 


>» Change /var/www/myproject to the filepath containing the sched folder from 
our project layout. 


>» Change /static/ if you changed the default static route in Flask. 
The updated server configuration, to handle static files: 


server { 

listen 80; 

server name localhost; 

access log /var/log/nginx/access.1log; 

error_log /var/log/nginx/error.log; 

location /static/ { 
# /static/ is appended to root path on the request. 
root /var/www/myproject/sched/; 

} 

location / { 
proxy pass http://127.0.0.1:5000/; 
proxy redirect off; 
proxy _set header Host Shost; 
proxy _set_header X-Real-IP Sremote_addr; 
proxy _set_header X-Forwarded-For $proxy_add_x forwarded_for; 


Deployable on any OS with HTTP proxying 


| prefer to run applications in production using HTTP proxying with application code served by 
stand-alone, independent operating system processes. Most industrial strength HTTP servers 
include a means to proxy requests to another web service, just as we demonstrated with nginx. 
gunicorn only runs on Unix-like systems, but cherrypy (cherrypy . org) provides a cross- 
platform WSGI server. You can start your application with a script which follows this example: 


from cherrypy.wsgiserver import CherryPyWSGIServer 
from sched.app import app 

server = CherryPyWSGIServer(('127.0.0.1', 5000), app) 
server.start () 
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Windows server deployment 


To run your Python application directly within Windows Server IIS, see the NWSGI project at 
nwsgi.codeplex.com. 


Other deployment options 
See the Flask docs at flask. pocoo.org/docs/deploying/. 
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